|
|
This Technote discusses addenda to the Inside Macintosh: QuickDraw GX Series.
This Note is intended for Macintosh QuickDraw GX developers who are using any version of QuickDraw GX up to and including 1.1.3.
Important for all Apple Printing and Graphics Developers:
The information in this Technote is still relevant up to and including
Mac OS 7.6
with QuickDraw GX 1.1.5. Beginning with the release of Mac OS 8.0,
however, Apple plans to deliver a system which incorporates QuickDraw GX
graphics and typography only. QuickDraw GX printer drivers and GX printing
extensions will not be supported in Mac OS 8.0 or in future Mac OS releases. Apple's
goal is to simplify the user experience of printing by unifying the Macintosh
graphic and printing architectures and standardizing on the classic Printing
Manager.
[Feb 1 1996]
|
Addendum to QuickDraw GX Environment and Utilities
GX Gestalt Versions
To determine the current version of QuickDraw GX in general, you call the Gestalt functions with the various gestalt selectors as outlined on p. 1-4 of Inside Macintosh: QuickDraw GX Environment and Utilities
. The function returns a value indicating the version of QuickDraw GX printing/graphics/etc. currently installed.
This is how the QuickDraw GX gestalt 'qdgx' works:
Table 1 shows you version gestalt values for QuickDraw GX.
'qdgx' Value GX Version
0x00010000 GX 1.0
0x00010001 GX 1.0.1
0x00010002 GX 1.0.2
0x00010100 GX 1.1
0x00010101 GX 1.1.1
0x00010102 GX 1.1.2
0x00010103 GX 1.1.3
|
Table 1 - Gestalt values for QuickDraw GX |
Back to top
Addendum to QuickDraw GX Objects
GXGetShapeClipType
You can use the GXGetShapeClipType function to retrieve the clip shape type that a shape is being clipped to.
gxShapeType GXGetShapeClipType(gxShape source)
source A reference to the shape you want to examine
the clip property of.
function result: A reference to the clip shape type.
|
DESCRIPTION
This function is used to determine just the clip shape and eliminates three expensive steps that were necessary in QuickDraw GX 1.0 to get this information.
The clip shape, which you specify using the clip parameter, may be a geometric shape, a bitmap shape, or a glyph shape. In the current implementation , it may not be a picture, text, or layout shape.
- If you specify a geometric shape, it must be in primitive form that is, all the
stylistic information about the shape must be incorporated into the shape's geometry because this function copies only the geometry-related information from the shape you specify. It does not copy the information contained in the shape's style. You can convert a shape to its primitive form using the GXPrimitiveShape function, which is described in Inside Macintosh: QuickDraw GX Graphics
. You can also specify an empty or full shape for a clip.
- If you specify a bitmap shape, it must have a pixel size of 1 and its color profile reference must be nil. In the bitmap, pixel values of 0 obscure drawing; pixel values of 1 do not restrict visibility.
- If you specify a glyph shape, this funciton uses information form the glyph shape's syle object as well as its style list to determine the size, form, and position of the glyph outlines; those outlines are then used to clip drawing. The syle list cannot have nil entries. A style object referenced by the glyph shape cannot be complex that is, it cannot have a cap, join, dash, pattern, text face, font variation, tag list, or any of the properties used only by layout
shapes.
ERRORS
out_of_memory
shape_is_nil
Back to top
Addenda to QuickDraw GX Printing Extensions and Drivers
PostScript Render Options
gxNoIllegalEPSOperator and gxEPSTargetOption flag have been added to PostScript Render Options.
enum
{
gxNeedsHexOption = 0x00000001,
gxNeedsCommentsOption = 0x00000002,
gxBoundingBoxesOption = 0x00000004,
gxPortablePostScriptOption = 0x00000008,
gxUseLevel2ColorOption = 0x00000080,
gxNoEPSIllegalOperators = 0x00000100,
gxEPSTargetOption = gxNoEPSIllegalOperators +
gxNeedsCommentsOption +
gxBoundingBoxesOption
};
typedef long gxPostScriptRenderOptions;
|
CONSTANT DESCRIPTIONS
gxNoEPSIllegalOperators The driver should only emit operators that are allowed
by Encapsulated PostScript specifications (Version 3.0).
gxEPSTargetOption The driver should issue PostScript intended for EPS
use.
|
For descriptions of other constants, please see Inside Macintosh: QuickDraw GX Printing Extensions and Drivers
, p. 4-27.
GXSetupPageImageData message
QuickDraw GX sends the GXSetupPageImageData message to indicate the final format, page shape, and imaging data for any given page. The message is sent once for every page, just prior to gxStartSendPage. You may wish to override this message in order to determine the final characteristics of the data which will be sent to the printer. Your override of the GXSetupPageImageData message must match the following declaration:
OSErr MySetupPageImageData(gxFormat theFormat, gxShape thePage,
void *imageData);
theFormat The format object for the page.
thePage A reference to the page shape.
imageData A pointer to imaging-specific data for
initializing the printing device.
function result: An error code. The value noErr indicates
that the operation was successful.
|
SPECIAL CONSIDERATIONS
You never send the GXSetupPageImageData message yourself. This message is not a device communications time message. Overrides should always forward this message.
RESULT CODES
gxSegmentLoadFailedErr A required code segment could not be found,
or there was not enough memory to load it.
gxPrUserAbortErr The user has canceled printing.
|
GXPostScriptEjectPendingPage message
QuickDraw GX sends the GXPostScriptEjectPendingPage message to check if there is a previously imaged page waiting to be ejected. If so, it will send the gxPostScriptEjectPage message for that page. Your override of the GXPostScriptEjectPendingPage message must match the following declaration:
OSErr MyPostScriptEjectPendingPage(Boolean *pageWasEjected)
*pageWasEjected A pointer to a Boolean value. On return,
the value is true if a page was ejected and
false otherwise.
function result: An error code. The value noErr indicates
that the operation was successful.
|
DESCRIPTION
You can override this message to implement your own page handling. If your driver is going to display a manual feed alert, it is usually desirable to eject the
previous page before asking the user to insert the next sheet of paper.
SPECIAL CONSIDERATIONS
Overrides should always forward this message.
RESULT CODES
gxSegmentLoadFailedErr A required code segment could not be found,
or there was not enough memory to load it.
gxPrUserAbortErr The user has canceled printing.
|
GXHandleAltDestination message
QuickDraw GX sends the GXHandleAltDestination message when a destination other than "Print" is selected in the Print dialog. Your override of the GXHandleAltDestination message must match the following declaration:
OSErr MyGXHandleAltDestination (Boolean *userCancels)
*userCancels A pointer to a Boolean value. On return, the
value is true if the user cancels.
function result: An error code. The value noErr indicates
that the operation was successful.
|
DESCRIPTION
This message is sent when the destination pop-up in the Print dialog is something other than Print. For instance, currently, if a user selects File in the
Print dialog, the Print button changes to Save. If you have a FAX driver and you want the Print dialog to be more user-friendly, you simply override this message to add your destination (e.g., TheFax) and to change the Save button to FAX for example.
SPECIAL CONSIDERATIONS
The override should check the gxFileFormatTag in the job collection. If the fileFormatName is an alternate destination, the driver or extension can either display its own dialog to get more information from the user or forward the message for the default 'Standard File' dialog.
In order to change the destination, you must have an alternate destination ('dsta') resource declared. For more information on the 'dsta' resource, continue reading this document.
RESULT CODES
gxSegmentLoadFailedErr A required code segment could not be found,
or there was not enough memory to load it.
gxPrUserAbortErr The user has canceled printing.
|
The Alternate Destination ('dsta') Resource
The alternate destination ('dsta') resource, of type gxDestinationAdditionType, allows a driver or application to specify a destination to be added to the destination pop-up menu in the Print dialog. Figure 1 shows the structure of the alternate destination resource.
Figure 1 - The alternate destination resource
destination name The Pascal string name to show in the print
dialog pop-up menu.
button text The Pascal string name to show in the "OK"
button when the user selects the destination
name from above in the pop-up menu.
|
The Custom Halftone Matrix ('dmat') Resource
The custom halftone matrix ('dmat') resource, of type gxCustomMatrixType, allows a driver or application to specify a custom halftone matrix to be used rather than one of the several built-in halftone dot types provided by QuickDraw GX. Figure 2 shows the structure of a custom halftone matrix.
Figure 2 - The custom halftone matrix resource
dpix The dots per inch in the x direction. This is a
fixed point value.
dpiy The dots per inch in the y direction. This is a
fixed point value.
width The width of the matrix.
height The height of the matrix.
brick offset The tile shift.
|
Each entry in the samples array is for a matrix that outlines a specific tile shift.
In order to make use of this resource, you must set the dither type of your 'rdip' resource to gxCustomDot.
For more information on the 'rdip' resource, please see Inside Macintosh: QuickDraw GX Printing Extensions and Drivers
, p. 6-66.
The Manual Feed Preferences ('mfpr') Resource
The manual feed preferences ('mfpr') resource, of type gxManualFeedAlertPrefsType, allows the disabling of manual feed alerts on a desktop printer. This resource is optional.
Figure 3 shows the structure of the manual feed preferences resource.
Figure 3: The manual feed preferences resource
alertFlags A collection of flag values that you can combine
together to specify when manual feed alerts
will be shown. The first word is for a driver's
private use.
|
Constant Value Explanation
gxShowAlerts 0x01 Tells GX to show alerts for this
desktop printer
|
Table 2 Flags used in the manual feed preferences resource
|
The default settings if no resource is found is gxDefaultMFeedAlertSettings (=gxShowAlerts | gxAlertOnPaperChange).
SPECIAL CONSIDERATIONS
The 'mfpr' and 'outp' resources must be stored in the desktop printer by sending the GXWriteDTPData message. The desktop printer is the only place QuickDraw GX looks for these resources. A driver might store these resources when the desktop printer is created by overriding GXDefaultDesktopPrinter, forwarding the message, and then using Send_GXWriteDTPData to write the data.
For more information on GXDefaultDesktopPrinter and GXWriteDTPData, see Inside Macintosh: QuickDraw GX Printing Extensions and Drivers
.
See the section "The Desktop Printer Output Characteristics ('outp') Resource" in this document for more information on 'outp'.
The Desktop Printer Output Characteristics ('outp') Resource
The Desktop Printer Output Characteristics ('outp') Resource, of type gxDriverOutputType, allows printer drivers to indicate the characteristics of a desktop printer's output device. Currently, this resource only indicates whether or not the desktop printer represents an output device that can be configurable to different paper types.
Figure 4 shows the structure of the desktop printer output characteristics resource.
Figure 4 - The desktop printer output characteristics resource
driverFlags Available for driver-defined options.
outputSettings A collection of flag values that you can
combine together to specify whether a
printer is a device with a paper feed.
Currently predefined with
gxCanConfigureTrays or 0.
|
Constant Value Explanation
gxCanConfigureTrays 0x01 Desktop printer represents a device
with a paper feed
|
Table 3 - Flags used in the manual feed preferences resource |
If no 'outp' resource is found in the desktop printers, QuickDraw GX assumes that the desktop printer is tray-configurable and will display the manual feed and paper mismatch alerts.
SPECIAL CONSIDERATIONS
The 'mfpr' and 'outp' resources must be stored in the desktop printer by sending the GXWriteDTPData message. The desktop printer is the only place QuickDraw GX looks for these resources. A driver might store these resources when the desktop printer is created by overriding GXDefaultDesktopPrinter, forwarding the message, and then using Send_GXWriteDTPData to write the data.
For more information on GXDefaultDesktopPrinter and GXWriteDTPData, see Inside Macintosh: QuickDraw GX Printing Extensions and Drivers
.
See the section "The Manual Feed Preferences ('mfpr') Resource" in this document for more information on 'mfpr'.
Change Default DTP 'pfpr' Apple Event
This Apple Event is used to change the current default desktop printer. In order to use it, you need to send an Apple Event of type 'pfpr' (not very mnemonic) to the printing extension (creator of 'pxtn') with the data of the event being the name of the desktop printer that you want to make the default. A good sample of this can be found on the Developer CD series: Tool Chest Edition under Tool Chest: QuickDraw GX: SetDefaultDTP.
|
WARNING:
'pfpr' is currently not a registered part of the Apple Event Suite.
|
Back to top
Addenda to QuickDraw GX Typography
GXGetLayoutJustificationGap
You can use the GXGetLayoutJustificationGap function to retrieve information about the amount of space QuickDraw GX tries to fill when justifying a line.
Fixed GXGetLayoutJustificationGap(gxShape layout)
layout A reference to the layout shape whose
information you need.
function result: The signed difference between the specified
width for the layout and the measured
(unjustified) width.
|
ERRORS
GXGetLayoutJustificationFactors
You can use the GXGetLayoutJustificationFactors function to retrieve information about how much space is added for different kinds of characters (such as kashida, whitespace, and non-whitespace) when a line is justified.
void GXGetLayoutJustificationFactors(gxShape layout, Fixed
constrainedFactors[], Fixed unconstrainedFactors[])
layout A reference to the layout shape whose information you need.
constrainedFactors
An array of Fixed values. On return, the array contains
factors that represent the portions of available padding
by priority (gxWhiteSpacePriority,..) that the layout
ended up using in order to justify the line.
unconstrainedFactors
An array of Fixed values. On return, the array contains
factors that represent the characters that were
designated as being able to absorb unlimited gap.
function result:
The signed difference between the specified
width for the layout and the measured
(unjustified) width.
|
ERRORS
GXGetFontDefaultFeatures
You can use the GXGetFontDefaultFeatures function to retrieve information about which layout features in a font happen by default.
long GXGetFontDefaultFeatures(gxFont fontID, gxRunFeature features[])
fontID A reference to the font whose information
you need.
features On return, an array of the features for
this font.
function result: A list of the feature type/selector pairs
that correspond to those features the font
designates as default behaviors.
|
ERRORS
out_of_memory
internal_font_error
illegal_font_parameter
|
Back to top
Downloadables
|
|
Acrobat version of this Note (531K).
|
Download
|
Back to top
| 
